Acorn User: China

home *** CD-ROM | disk | FTP | other *** search

/ Acorn User: China / Acorn User China CD-ROM (UK) (Disc B) / Acorn User China CD-ROM (UK) (Disc B).bin / STUTTGART / DATABASE / INDICES0 / !Indices│ / !Help next >

Wrap

Text File | 1995-01-27 | 14.5 KB | 358 lines

Indices³ v0.86 RISC OS 3 Programmer's Reference Manual Indices by Tracy of SICK & Svlad compiled by Merlin Hughes & Svlad Cjelli the RISC OS 3 PRMs are Copyright © 1992 Acorn Computers Limited all rights reserved this software copyright © 1995 SICK (Merlin Hughes, Conrad Hughes & Andrew Block) 15 January 1995 -o- Many thanks to Acorn for producing the RO3 PRMs and giving permission for the index sections included here to be distributed in this application. -o- This application provides an electronic index of the RISC OS 3 Programmer's Reference Manuals, and a Wimp and CLI front end for searching through this. For the Wimp front end to function correctly, it must have write access to <Wimp$ScrapDir>. -o- When you run this application, an icon appears on the icon-bar letting you easily search the index files. Simply click select or adjust on the icon, and a search window will pop up. Type your request in, hit return, and the search will start. The output will soon jump up in an editor window. A beep indicates that there were no matches. For example, to search for PRM references to 'Pointer', type 'Pointer' (without the quotes) into the search window. Output lists the volume number, page number, operation, and description (eg "1-637 OS_Byte 106 Select pointer / activate mouse"). In this case, it is volume 1, page 637, operation 'OS_Byte 106', and an associated description. -o- If you click menu on the icon, a small menu appears: . 'Info' leads to the normal information window. . 'Options' leads to an options window. . 'Quit' quits the Wimp task; it does not kill the module. -o- The options window provides the following functions: . If 'Clear search window' is selected, whenever the search window is opened, the search text is cleared. Otherwise it retains the text last entered into it. . If 'Search in taskwindow' is selected, searches are performed in a task-window; this runs the search in the background allowing you to do some work during the moments of the search. . If 'Install in Resources' is selected, the index files are installed in ResourceFS when the Wimp task is started (and when you click on the OK button); otherwise, searches run from disk. . If 'Hot key' is selected, a certain keypress will pop the search window up under the pointer. To choose this key, click in the box beside the option button; it will invert, waiting for you to press a key; the key you press becomes the new hot key. Thus, if you want Ctrl-F1 to bring up the search window, press Ctrl-F1 when the box is inverted. The number inside the box is the Wimp code for the current hot key. The search window may not pop up if you hit the hot key while the caret is inside a window. . If 'Buffer file in RMA' is selected, the output of a search is stored in the RMA before being written to disk. This may considerably speed things up, and should not lead to RMA fragmentation. It will temporarily require a bit more free memory than would the resulting output file. It will have no effect if 'Search in taskwindow' is selected. . 'OK' accepts the state of the option buttons. Until you click on this, operation continues regardless of any changes in the option buttons; click on this to accept your choices. . 'Save' accepts and saves the options. These are then the default settings for when you next use the indices. . 'Cancel' cancels your selection and retains the original state of the options. -o- The searching facilities are fairly sophisticated; the matching is wildcarded case insensitive. This means that you do not have to get the capital letters in the right places, nor do you have to type in the complete name of the search topic. Thus looking for 'POInt' is as good as 'Pointer'; it will match a few more cases ('Floating Point' etc.) but involves less typing. There is also a single-character wildcard; wherever a '.' occurs in the search string, any character will match it. Thus 'P.int' will match both 'Point' and 'Print'. The indices are separated into several files corresponding to the different sections they cover. For example, SWIs are stored in a 'SWI' file while information on reason codes is stored in a 'Reason' file. If you want to just search a particular file, start your search with '-<section>'. For example, '-SWI Point' will match 'Point' in the file 'SWI'. If you want to search several sections, simply separate them by commas. To search in the files 'Reason' and 'Poll', type '-Reason,Poll Point'. You may not put any spaces in this list; '-SWI, Poll' is invalid. You do not have to remember exact section names either; the filename matching is also wildcarded, so '-Re,Po Poi' is just as good as '-Reason,Poll Pointer'. By default, searches do not cover all sections; they only cover a basic set. If you want to search all sections, start your search with '-' on its own. This in fact does a wildcard match on an empty file list, which matches everything. Thus searching for '- Plot' will match more than if you just search for 'Plot'. The basic search set is defined by the 'Indices$Search' system variable, which is set in the !Run file. If you supply no search string at all, this help file is listed; if you supply a list of search files, but no search string, (such as '-Swi,Reas'), the entire contents of the specified sections will be listed. Searching for the string '@File' will throw the first index file which matches 'File*' into an editor window. This lets you quickly edit index files. -o- The following is a list of example searches: Search: Output: 'mod' Standard references to 'mod' '- mod' ALL references to 'mod' '-swi mod' SWI references to 'mod' '-reas,pol mou' Reason or Poll references to 'mou' '-cont' Table of contents '-' Everything -o- The currently supplied sections are as follows: Command - list of *commands Contents - list of contents Event - list of events FileType - list of file types Format - list of file format descriptions Inkey - list of negative inkey numbers Message - list of Wimp messages OS_Args - list of OS_Args calls OS_Byte - list of OS_Byte calls OS_File - list of OS_File calls OS_Find - list of OS_Find calls OS_FSCtrl - list of OS_FSControl calls OS_GBPB - list of OS_GBPB calls OS_Module - list of OS_Module calls OS_SpriteO - list of OS_SpriteOp calls OS_Word - list of OS_Word calls Phone - a phone book with me in it Poll - list of Wimp_Poll reason codes Reason - information on reason codes Service - list of module service calls SWI - list of kernel SWIs VDU - list of VDU calls Vector - list of software vectors The default searching set is: Contents OS_Byte OS_Word SWI Command Service Poll -o- The indices module supplies several *Commands: . *Index performs the search from the command-line; parameters are exactly the same as the searches which I have described above. Typing '*Index Poi' will thus list index matches of 'Poi'. . *DesIndex performs exactly the same function as *Index, but puts the matches in the file 'LocalIndex:Results' and throws this back into an editor window. It can be run from the command line, but if more than one search is performed, the former outputs will be overwritten by the last one. If LocalIndex$Path is not defined, output goes to 'Index:Results'. The file is NOT removed after display. . *ResoIndices installs the index files in ResourceFS for fast searching at a cost of around 80Kb. If you set the option in the Options window, this is done automatically at startup. . *DiscIndices de-installs the index files from ResourceFS and returns to accessing them on disk, thus freeing some RMA space. . *WimpIndices starts up the indices Wimp task. This should be issued from the Switcher 'New task' menu. -o- If you want to use this completely from the command line (never entering the desktop), run the !Install file; this installs the module so you can do the searches from disk. You MUST run the !Install command file with a full pathname; otherwise this won't know where the indices truly are. As an example, put the following Obeyfile (called 'Index') in your Library: */scsi::Apocalypse.$.Utils.!Indices³.!Install *Index %*0 When you first type '*Index foo', this will install the indices and perform your search; subsequently searches won't run this obey script, they will run from the module. If you stick '*ResoIndices' in between the two lines above, the indices will be automatically put in ResourceFS. Note: This does not define the 'LocalIndex$Path', so if you subsequently use '*DesIndex', or the Wimp front end without running !Indices³, output will go into the main application directory. -o- Warning: use of '*DesIndex' (and thus the Wimp front-end) from a shared filing system requires Wimp$ScrapDir to be local to each user. Otherwise if two people use the same file, complications will occur. If you don't want to use Wimp$ScrapDir, change the !Run file - comment out the lines altogether if you want. Output will then go into this application. This module and the variables and resources necessary to use the indices all survive a soft-reset. If you find any mistakes in existing files, or you add your own bit of an index, please mail it to me (see address below) and I'll suitably alter the release version. -o- Searching is done with the 'Isrch' utility. This is located in '!Indices³.Resources' and is a fairly general-purpose search utility. If you just run it with no parameters, it gives some help. There is also an 'Asrch' application; this is a modified Isrch which runs in application space; the taskwindow does not multi-task the 'Isrch' utility searcher. 'Asrch' should not be used outside this application; it always forces throwback of the output file. 'Msrch' is a version of 'Isrch' which buffers the output in RMA. -o- If you change the indices and want to re-install them into ResourceFS, just type '*ResoIndices' or re-run the application. The old files will be freed from ResourceFS automatically. -o- This application is FreeWare. That is to say, permission is granted by me for anyone to distribute this application, unchanged and in its entirety, providing that no profit is made in the process. The application may not be distributed if modified or if incomplete; neither may parts of it be distributed separately. Thus, without express permission, you may not distribute the index files herein separately from this application. Public domain libraries and such institutions may charge NO MORE THAN £1.00 for distribution on a medium as cheap as a double-density disk, and NO MORE THAN £2.00 on a more expensive medium such as a high-density disk. This limit includes all charges; post, packaging, and copying, and applies before any special discounts. It may NOT be distributed along with any other chargeable product; such as a big magazine or more expensive disk. If in doubt, try and contact me. What with my current lack of fixed abode, try electronic means in preference to solid means. This product is supplied as is; there is no warranty for it. No warranty, expressed or implied, including but not limited to, the implied warranties of merchantability and fitness for a particular purpose, will be considered valid. The entire risk as to the quality and performance of the program is with you. You assume any costs that may emerge as a result of this product, its use, misuse, abuse, or as a result of any other phenomenon associated it. In no event will the copyright holders, Acorn, or any other parties who distribute this product, be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use of or inability to use this product (including, but not limited to, loss of data, or data being rendered inaccurate, or losses sustained by you or third parties, or a failure of the program to operate with any other programs). -o- Address: Merlin Hughes, Department of Computer Science, CB#3175 Sitterson Hall, University of North Carolina at Chapel Hill, Chapel Hill, NC 27599-3175, U.S.A. Office Phone: +1-919-962-1909 Home Phone: +1-919-968-1674 Internet: hughesm@cs.unc.edu merlin@maths.tcd.ie merlin@scrg.cs.tcd.ie chughes@maths.tcd.ie Contact me through my mum at: Address: Merlin Hughes, 14 Kenilworth Park, Harold's Cross, Dublin 6W, Eire. Phone: +353-1-4901237 -o- Thanx to Tom Hughes, Andrew Brooks, Dean Murphy, and David Bell, who variously helped in the production of this. -o- Please, as I say, if you find any mistakes, add any useful indices, or write a better browser, mail me so I can include them for everyone. Merlin.